<!DOCTYPE HTML>
<html>
<head>
<title>FileRead | AutoHotkey</title>
<meta name="description" content="The FileRead command reads a file's contents into a variable." />
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>FileRead</h1>

<p>读取文件的内容到<a href="../Variables.htm">变量</a>.</p>

<pre class="Syntax"><span class="func">FileRead</span>, OutputVar, Filename</pre>
<h2>参数</h2>
<dl>

  <dt>OutputVar</dt>
  <dd><p>用来存储获取的数据的<a href="../Variables.htm">变量</a>名. 如果遇到问题, 例如文件"在使用中"或不存在, 则 <em>OutputVar</em> 被置空(此时 <a href="../misc/ErrorLevel.htm">ErrorLevel</a> 被设置为 1). 如果 <em>Filename</em> 是个空文件, 则输出变量也被置空(此时 ErrorLevel 被置为 0).</p></dd>

  <dt>Filename</dt>
  <dd><p>要读取的文件名, 如果未指定绝对路径则假定在 <a href="../Variables.htm#WorkingDir">%A_WorkingDir%</a> 中.</p>
      <p><strong>选项</strong>: 在文件名前面可以直接添加零个或多个下列字符串. 在选项间使用单个空格或 tab 分隔. 例如: <code>*t *m5000 C:\Log Files\200601.txt</code>.</p>
    <p><strong>*c</strong>: 读取保存了 <a href="../misc/Clipboard.htm#ClipboardAll">ClipboardAll</a> 内容的文件或其他二进制数据. 使用了 <strong>*c</strong> 选项时其他所有选项会被忽略.</p>
    <p><strong>*m1024</strong>: 如果省略此选项, 则读取整个文件, 不过如果内存不足, 则显示错误消息并退出线程(使用 <a href="Try.htm">Try</a> 可以避免这种情况). 否则, 请把 1024 替换为十进制或十六进制表示的字节数. 如果文件大于此字节数, 那么只读取其前面部分.</p>
<p class="note"><strong>注意</strong>: 此选项可能导致最后一行以单独的回车符(`r) 而不是 `r`n 结束.</p>    
    <p><strong>*t</strong>: 把所有的回车换行符(`r`n) 替换为换行符(`n). 不过, 这种转换会降低性能而且往往不必要. 例如, 包含 `r`n 的文本已经是添加到 <a href="GuiControls.htm#Edit">Gui 编辑控件</a>的正确格式. 同样地, <a href="FileAppend.htm">FileAppend</a> 打开新文件时会检测是否含有 `r`n; 它知道按原样写入每对 `r`n 而不是把它转换成 `r`r`n. 最后, 不论每行的结束符是 `r`n 或只是 `n, 后面的<a href="LoopParse.htm">解析循环</a>都可以正确执行: <code>Loop, parse, MyFileContents, `n, `r</code>.</p>
    <p><strong>*Pnnn</strong>: <span class="ver">[AHK_L 42+]:</span> 覆盖 <a href="FileEncoding.htm">FileEncoding</a> 包含的默认编码设置, 其中 <em>nnn</em> 必须是数值的<a href="http://msdn.microsoft.com/en-us/library/dd317756.aspx">代码页标识符</a>.</p></dd>

</dl>

<h2>ErrorLevel</h2>
<p><span class="ver">[v1.1.04+]</span>: 此命令失败时会抛出异常. 想了解更多信息, 请参阅<a href="Catch.htm#RuntimeErrors">运行时错误</a>.</p>
<p>读取成功时 <a href="../misc/ErrorLevel.htm">ErrorLevel</a> 被置为 0. 如果遇到问题, 它被设置为 1, 例如: 1) 文件不存在; 2) 文件被锁定或无法访问; 3) 系统没有足够的内存加载文件.</p>
<p><a href="../Variables.htm#LastError">A_LastError</a> 被设置为操作系统 GetLastError() 函数返回的结果.</p>

<h2 id="Binary">读取二进制数据</h2>
<p>根据文件, 参数和默认设置, FileRead 可能把文件数据解释为文本并且把它转换成脚本使用的<a href="../Compat.htm#Format">原生编码</a>. 如果文件包含二进制数据, 那么这样的操作很可能引起问题, 不过在下列情况中则可以避免:</p>
<ul>
  <li>如果存在 <span class="Syntax">*C</span> 选项, 则无条件忽略所有代码页和行结束符的转换.</li>
  <li>如果存在 <span class="Syntax">*P<i>nnn</i></span> 选项且 <i>nnn</i> 符合原生的字符串编码, 则不会进行代码页转换.</li>
  <li>如果当前<a href="FileEncoding.htm">文件编码</a>设置符合原生字符串编码, 则不会进行代码页转换.</li>
</ul>
<p>注意一旦把数据读取到 <em>OutputVar</em>, 那么只有首个二进制零(如果存在) 才能被大多数 AutoHotkey 命令和函数 "看到". 然而, 所有的内容仍然存在并且可以使用高级的方法进行访问(例如 <a href="NumGet.htm">NumGet()</a>).</p>
<p>最后, 使用 <a href="FileOpen.htm">FileOpen()</a> 和 <a href="../objects/File.htm#RawRead">File.RawRead()</a> 或 <a href="../objects/File.htm#ReadNum">File.Read<i>Num</i>()</a> 可以在无需首先读取整个文件到内存中的情况下读取二进制数据.</p>

<h2>备注</h2>
<p>当需要读取文件的全部或大部分内容到内存时, 使用 FileRead 比<a href="LoopReadFile.htm">文件读取循环</a>执行地更好.</p>
<p>大于 1 GB 的文件会导致 <a href="../misc/ErrorLevel.htm">ErrorLevel</a> 被设置为 1 并且 <em>OutputVar</em> 被置为空, 此时可以使用 <strong>*m</strong> 选项来避免并读取文件的前面部分.</p>
<p>FileRead 不遵循 <a href="_MaxMem.htm">#MaxMem</a> 的设置. 如果担心使用太多的内存, 可以预先用 <a href="FileGetSize.htm">FileGetSize</a> 检查文件的大小.</p>
<p><a href="FileOpen.htm">FileOpen()</a> 比 FileRead 提供了更高级的功能, 例如在文件的指定位置读取或写入数据时无需把整个文件读取到内存中. 请参阅<a href="../objects/File.htm">文件对象</a>了解函数列表.</p>

<h2>相关</h2>
<p><a href="FileEncoding.htm">FileEncoding</a>, <a href="FileOpen.htm">FileOpen</a>/<a href="../objects/File.htm">File Object</a>, <a href="LoopReadFile.htm">文件读取循环</a>, <a href="FileReadLine.htm">FileReadLine</a>, <a href="FileGetSize.htm">FileGetSize</a>, <a href="FileAppend.htm">FileAppend</a>, <a href="IniRead.htm">IniRead</a>, <a href="Sort.htm">Sort</a>, <a href="URLDownloadToFile.htm">UrlDownloadToFile</a></p>

<h2>示例</h2>
<pre class="NoIndent" id="ex1"><em>; 示例 #1: 读取文本文件到 OutputVar.</em>
FileRead, OutputVar, C:\My Documents\My File.txt</pre>
<pre class="NoIndent" id="ex2"><em>; 示例 #2: 快速对文件的内容进行排序.</em>
FileRead, Contents, C:\Address List.txt
if not ErrorLevel  <em>; 加载成功</em>
{
    <a href="Sort.htm">Sort</a>, Contents
    FileDelete, C:\Address List (alphabetical).txt
    FileAppend, %Contents%, C:\Address List (alphabetical).txt
    Contents =  <em>; 清空占用的内存.</em>
}</pre>

</body>
</html>